home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / getpwent.z / getpwent
Encoding:
Text File  |  1998-10-20  |  11.7 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))                                                      GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r,
  10.      setpwent, endpwent, fgetpwent, fgetpwent_r - get password file entry
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppwwwwdddd....hhhh>>>>
  14.  
  15.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ggggeeeettttppppwwwweeeennnntttt((((vvvvooooiiiidddd))));;;;
  16.  
  17.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ggggeeeettttppppwwwweeeennnntttt____rrrr((((ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ppppwwwweeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, ssssiiiizzzzeeee____tttt bbbbuuuuffffssssiiiizzzzeeee))));;;;
  18.  
  19.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ggggeeeettttppppwwwwuuuuiiiidddd((((uuuuiiiidddd____tttt uuuuiiiidddd))));;;;
  20.  
  21.      iiiinnnntttt ggggeeeettttppppwwwwuuuuiiiidddd____rrrr((((uuuuiiiidddd____tttt uuuuiiiidddd,,,, ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ppppwwwweeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, ssssiiiizzzzeeee____tttt bbbbuuuuffffssssiiiizzzzeeee,,,, ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ********rrrreeeessssuuuulllltttt))));;;;
  22.  
  23.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ggggeeeettttppppwwwwnnnnaaaammmm((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;;
  24.  
  25.      iiiinnnntttt ggggeeeettttppppwwwwnnnnaaaammmm____rrrr((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ppppwwwweeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, ssssiiiizzzzeeee____tttt bbbbuuuuffffssssiiiizzzzeeee,,,, ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ********rrrreeeessssuuuulllltttt))));;;;
  26.  
  27.      vvvvooooiiiidddd sssseeeettttppppwwwweeeennnntttt((((vvvvooooiiiidddd))));;;;
  28.  
  29.      vvvvooooiiiidddd eeeennnnddddppppwwwweeeennnntttt((((vvvvooooiiiidddd))));;;;
  30.  
  31.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ffffggggeeeettttppppwwwweeeennnntttt((((FFFFIIIILLLLEEEE ****ffff))));;;;
  32.  
  33.      ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ffffggggeeeettttppppwwwweeeennnntttt____rrrr((((FFFFIIIILLLLEEEE ****ffff,,,, ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd ****ppppwwwweeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, ssssiiiizzzzeeee____tttt bbbbuuuuffffssssiiiizzzzeeee))));;;;
  34.  
  35.      eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ____ggggeeeettttppppwwwweeeennnntttt____nnnnoooo____yyyypppp;;;;
  36.  
  37.      eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ____ggggeeeettttppppwwwweeeennnntttt____nnnnoooo____sssshhhhaaaaddddoooowwww;;;;
  38.  
  39.      eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ____ppppwwww____ssssttttaaaayyyyooooppppeeeennnn;;;;
  40.  
  41. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  42.      _g_e_t_p_w_e_n_t, _g_e_t_p_w_u_i_d , _g_e_t_p_w_n_a_m and their reentrant counterparts each
  43.      return a pointer to an object with the following structure containing the
  44.      broken-out fields of a line in the /_e_t_c/_p_a_s_s_w_d file or some other back-
  45.      end database.  Each line in the file contains a ``passwd'' structure,
  46.      declared in the <_p_w_d._h> header file:
  47.  
  48.           struct passwd {
  49.                char *pw_name;
  50.                char *pw_passwd;
  51.                uid_t     pw_uid;
  52.                gid_t     pw_gid;
  53.                char *pw_age;
  54.                char *pw_comment;
  55.                char *pw_gecos;
  56.                char *pw_dir;
  57.                char *pw_shell;
  58.           };
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))                                                      GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      This structure is declared in <_p_w_d._h> so it is not necessary to redeclare
  75.      it.
  76.  
  77.      The fields have meanings described in _p_a_s_s_w_d(4).
  78.  
  79.      _g_e_t_p_w_e_n_t when first called returns a pointer to the first passwd
  80.      structure in the file; thereafter, it returns a pointer to the next
  81.      passwd structure in the file; so successive calls can be used to search
  82.      the entire file.  _g_e_t_p_w_u_i_d searches from the beginning of the file until
  83.      a numerical user id matching _u_i_d is found and returns a pointer to the
  84.      particular structure in which it was found.  _g_e_t_p_w_n_a_m searches from the
  85.      beginning of the file until a login name matching _n_a_m_e is found, and
  86.      returns a pointer to the particular structure in which it was found.  If
  87.      an end-of-file or an error is encountered on reading, these functions
  88.      return a NULL pointer.
  89.  
  90.      The _g_e_t_p_w_n_a_m__r and _g_e_t_p_w_u_i_d__r calls are reentrant versions of the
  91.      _g_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d calls.  The extra arguments are pwent, buffer are
  92.      used for internal storage, bufsize is the size of buffer, and result is
  93.      the struct passwd used to return the requested information.    A good
  94.      size of buffer is BUFSIZ bytes.
  95.  
  96.      A call to _s_e_t_p_w_e_n_t has the effect of rewinding the password file to allow
  97.      repeated searches.  _e_n_d_p_w_e_n_t may be called to close the password file
  98.      when processing is complete.
  99.  
  100.      _f_g_e_t_p_w_e_n_t returns a pointer to the next passwd structure in the stream _f,
  101.      which matches the format of /_e_t_c/_p_a_s_s_w_d.
  102.  
  103.      The routines getpwent, fgetpwent, getpwnam and getpwuid all return data
  104.      from a statically allocated space which is overwritten on each call.
  105.      Reentrant versions of these routines getpwent_r, fgetpwent_r, getpwnam_r,
  106.      and getpwuid_r are provided which will parse the result into supplied
  107.      space.  Each takes three extra arguments, a pointer to a struct passwd
  108.      structure, a pointer to a character buffer, and a length for the buffer.
  109.  
  110. NNNNOOOOTTTTEEEESSSS
  111.      In IRIX 4.0, there were two versions of the getpwent primitives:  the
  112.      standard version in _llll_iiii_bbbb_cccc and the NIS version in _llll_iiii_bbbb_ssss_uuuu_nnnn.  The routines in
  113.      this release only parse files in the format given in passwd(4).  Either
  114.      the static file /_e_t_c/_p_a_s_s_w_d or a dynamic file supplied by the nsd(1M)
  115.      daemon.  The nsd daemon can supply data from any number of back-end
  116.      databases or protocols as controlled by the nsd configuration file
  117.      /_e_t_c/_n_s_s_w_i_t_c_h._c_o_n_f.  To force these routines to use only the static file
  118.      set the external variable __g_e_t_p_w_e_n_t__n_o__y_p to 1.  This is only really
  119.      useful for programs that will use this information in subsequent
  120.      _p_u_t_p_w_e_n_t(3C) calls (otherwise, the entire back-end database will be
  121.      copied to /_e_t_c/_p_a_s_s_w_d).  __g_e_t_p_w_e_n_t__n_o__y_p is understood by _g_e_t_p_w_e_n_t,
  122.      _g_e_t_p_w_n_a_m, _g_e_t_p_w_u_i_d and their reentrant counterparts.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))                                                      GGGGEEEETTTTPPPPWWWWEEEENNNNTTTT((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      For _g_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d only, if the file /_e_t_c/_s_h_a_d_o_w is present, and
  141.      the current effective user ID is root, the password entry will be copied
  142.      out of /_e_t_c/_s_h_a_d_o_w and placed in the _p_w__p_a_s_s_w_d field.  This compatibility
  143.      feature permits programs expecting password information to be in
  144.      /_e_t_c/_p_a_s_s_w_d to function properly in a shadow password environment.  Note
  145.      that the aging information from /_e_t_c/_s_h_a_d_o_w is not made available in
  146.      _p_w__a_g_e.  For portability to other systems, the existence of /_e_t_c/_s_h_a_d_o_w
  147.      should be dealt with by the program, not this interface (see
  148.      _g_e_t_s_p_e_n_t(3C)).  To disable this behavior (for example, to make a verbatim
  149.      copy of /_e_t_c/_p_a_s_s_w_d using _p_u_t_p_w_e_n_t(3C)), set the external variable
  150.      __g_e_t_p_w_e_n_t__n_o__s_h_a_d_o_w to 1.
  151.  
  152.      To cause the password file to be left open until an explicit call to
  153.      _e_n_d_p_w_e_n_t(3C), set the external variable __p_w__s_t_a_y_o_p_e_n to 1.
  154.  
  155.      By default, __g_e_t_p_w_e_n_t__n_o__y_p, __g_e_t_p_w_e_n_t__n_o__s_h_a_d_o_w, and __p_w__s_t_a_y_o_p_e_n are 0.
  156.  
  157.      The Mips ABI specifies nothing but local files so applications which wish
  158.      to use anything else must compile with libc prior to libnsl in the
  159.      library list.
  160.  
  161.      When nsd is running changes to the local passwd file may not be noticed
  162.      by getpwent() until the enumeration cache file has timed out.
  163.  
  164. FFFFIIIILLLLEEEESSSS
  165.      /etc/passwd /var/ns/cache/passwd.byname.m /var/ns/cache/passwd.byuid.m
  166.  
  167. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  168.      nsd(1M), getlogin(3C), getgrent(3C), getspent(3C), passwd(4), shadow(4)
  169.      fopen(3S).
  170.  
  171. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  172.      A NNNNUUUULLLLLLLL pointer is returned on EEEEOOOOFFFF or error.
  173.  
  174. BBBBUUUUGGGGSSSS
  175.      All of the functions use _f_o_p_e_n(3S) and are thus subject to its
  176.      limitations.
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.